---
layout: default
type: plugin
permalink: :path
breadcrumbs:
  Hub: '/hub'

---

{% if page.type == "plugin" %}

{% capture config_required_fields %}{%
  for field in page.params.config %}{%
  if field.value_in_examples != nil %}{%
  if field.value_in_examples.first %}{%
  for value in field.value_in_examples %} \
    --data{% if field.urlencode_in_examples %}-urlencode{% endif %} "config.{{ field.name }}={{ value }}"{%
  endfor %}{%
  else %} \
    --data{% if field.urlencode_in_examples %}-urlencode{% endif %} "config.{{ field.name }}={{ field.value_in_examples }}"{%
  endif %}{%
  elsif field.required == true %} \
    --data{% if field.urlencode_in_examples %}-urlencode{% endif %} "config.{{ field.name }}={{ field.default | markdownify | strip_html | strip }}"{%
  endif %}{% endfor
%}{% endcapture %}

{% capture config_required_fields_yaml
  %}config: {%
  for field in page.params.config %}{%
  if field.value_in_examples != nil %}{%
    if field.value_in_examples.first %}
    {{ field.name }}:{%
    for value in field.value_in_examples %}
    - {{ value }}{%
    endfor %}{%
    else %}
    {{ field.name }}: {{ field.value_in_examples }}{%
    endif %}{%
  elsif field.required == true %}
    {{ field.name }}: {{ field.default | markdownify | strip_html | strip }}{%
  endif %}{% endfor
%}{% endcapture %}

{% if page.params.service_id %}
{% capture plugin_config_for_service_with_db %}

Configure this plugin on a [Service](/latest/admin-api/#service-object) by
making the following request:

```bash
$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name={{page.params.name}}" {{ config_required_fields }}
```
{% endcapture %}

{% capture plugin_config_for_service %}
### Enabling the plugin on a Service

{% if page.enterprise %}

{{ plugin_config_for_service_with_db }}

{% else %}

{% navtabs %}
{% navtab With a database %}

{{ plugin_config_for_service_with_db }}

{% endnavtab %}
{% navtab Without a database %}

Configure this plugin on a [Service](/latest/admin-api/#service-object) by
adding this section to your declarative configuration file:

``` yaml
plugins:
- name: {{page.params.name}}
  service: {service}
  {{ config_required_fields_yaml }}
```
{% endnavtab %}
{% endnavtabs %}

{% endif %}

`{service}` is the `id` or `name` of the Service that this plugin configuration will target.

{% endcapture %}
{% endif %}

{% if page.params.route_id %}

{% capture plugin_config_for_route_with_db %}

Configure this plugin on a [Route](/latest/admin-api/#Route-object) with:

```bash
$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name={{page.params.name}}" {{ config_required_fields }}
```
{% endcapture %}

{% capture plugin_config_for_route %}
### Enabling the plugin on a Route

{% if page.enterprise %}

{{ plugin_config_for_route_with_db }}

{% else %}

{% navtabs %}
{% navtab With a database %}

{{ plugin_config_for_route_with_db }}

{% endnavtab %}
{% navtab Without a database %}

Configure this plugin on a [Route](/latest/admin-api/#route-object) by
adding this section to your declarative configuration file:

``` yaml
plugins:
- name: {{page.params.name}}
  route: {route}
  {{ config_required_fields_yaml }}
```
{% endnavtab %}
{% endnavtabs %}
{% endif %}

`{route}` is the `id` or `name` of the Route that this plugin configuration will target.

{% endcapture %}
{% endif %}

{% if page.params.consumer_id %}
{% capture plugin_config_for_consumer_with_db %}

You can use the `http://localhost:8001/plugins` endpoint to enable this plugin
on specific [Consumers](/latest/admin-api/#Consumer-object):

```bash
$ curl -X POST http://kong:8001/consumers/{consumer}/plugins \
    --data "name={{page.params.name}}" \
    {{ config_required_fields }}
```
{% endcapture %}

{% capture plugin_config_for_consumer %}
### Enabling the plugin on a Consumer

{% if page.enterprise %}

{{ plugin_config_for_consumer_with_db }}

{% else %}
{% navtabs %}

{% navtab With a database %}

{{ plugin_config_for_consumer_with_db }}

{% endnavtab %}
{% navtab Without a database %}

Configure this plugin on a [Consumer](/latest/admin-api/#consumer-object) by
adding this section to your declarative configuration file:

``` yaml
plugins:
- name: {{page.params.name}}
  consumer: {consumer}
  {{ config_required_fields_yaml }}
```
{% endnavtab %}
{% endnavtabs %}
{% endif %}

`{consumer}` is the `id` or `username` of the Consumer that this plugin configuration will target.

{% if page.params.service_id or page.params_route_id or page.params.api_id %}
You can combine `consumer.id` and {%
  if page.params.service_id %}`service.id`{%
  elsif page.params.route_id %}`route.id`{%
  elsif page.params.api_id %}`api_id`{%
  endif %} in the same request, to further narrow the scope of the plugin.
{% endif %}

{% endcapture %}
{% endif %}

{% if page.params.api_id %}
{% capture plugin_config_for_api %}
### Enabling the plugin on an API

If you are using an older version of Kong with the legacy [API
entity](/0.13.x/admin-api/#api-object) (**deprecated** in favor of Services
since <a href="https://github.com/Kong/kong/blob/master/CHANGELOG.md#0130---20180322">
CE 0.13.0</a> and
<a href="https://docs.konghq.com/enterprise/changelog/#0-32">EE 0.32</a>.), you
can configure this plugin on top of such an API by making the following request:

```bash
$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name={{page.params.name}}" {{ config_required_fields }}
```

* `api`: either id or name of the API that this plugin configuration will
  target.
{% endcapture %}
{% endif %}

{% capture params_table %}
<table>
  <thead>
    <tr><th>Form Parameter</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr><td><code>name</code></td><td>The name of the plugin to use, in this case <code>{{ page.params.name }}</code></td></tr>

    {% if page.params.service_id %}
      <tr><td><code>service.id</code></td><td>The ID of the Service the plugin targets.</td></tr>
    {% endif %}
    {% if page.params.route_id %}
      <tr><td><code>route.id</code></td><td>The ID of the Route the plugin targets.</td></tr>
    {% endif %}
    {% if page.params.consumer_id %}
      <tr><td><code>consumer.id</code></td><td>The ID of the Consumer the plugin targets.</td></tr>
    {% endif %}
      <tr><td><code>enabled</code><br><br><strong>default value: </strong><code>true</code></td><td>Whether this plugin will be applied.</td></tr>
    {% if page.params.api_id %}
    <tr><td><code>api_id</code></td><td>The ID of the API the plugin targets. <br><br><strong>Note:</strong> The <a href="/0.13.x/admin-api/#api-object">API Entity</a> is deprecated in favor of Services since <a href="https://github.com/Kong/kong/blob/master/CHANGELOG.md#0130---20180322">CE 0.13.0</a> and <a href="https://docs.konghq.com/enterprise/changelog/#0-32">EE 0.32</a>.</td></tr>
    {% endif %}
    {% for field in page.params.config %}
      <tr>
        <td><code>config.{{ field.name }}</code>
          {% if field.required == false %}<br><em>optional</em>{% endif %}
          {% if field.required == "semi" %}<br><em>semi-optional</em>{% endif %}
          {% if field.default != nil %}<br><br><strong>default value: </strong>{{ field.default | markdownify }}{% endif %}
        </td>
        <td>{{ field.description | markdownify }}</td>
      </tr>
    {% endfor %}
  </tbody>
</table>
{% endcapture %}

{% endif %}

{% if page.kong_version_compatibility.community_edition %}
  {% assign compat = true %}
  {% assign ce_compatible = page.kong_version_compatibility.community_edition.compatible %}
  {% assign ce_incompatible = page.kong_version_compatibility.community_edition.incompatible %}
{% endif %}
{% if page.kong_version_compatibility.enterprise_edition %}
  {% assign compat = true %}
  {% assign ee_compatible = page.kong_version_compatibility.enterprise_edition.compatible %}
  {% assign ee_incompatible = page.kong_version_compatibility.enterprise_edition.incompatible %}
{% endif %}

{% assign extn_type = site.extensions.types | where: "slug", page.type %}
{% assign extn_type = extn_type[0]['name'] %}
{% assign path_array = page.path | split: "/" %}
{% assign extn_slug = path_array[2] %}
{% assign extn_publisher = path_array[1] %}
{% capture extn_id %}{{ extn_publisher }}_{{ extn_slug }}{% endcapture %}
{% capture extn_icon %}/assets/images/icons/hub/{{ extn_id }}.png{% endcapture %}
{% assign extn_filename = path_array | last %}
{% assign extn_versions = site.data.extensions[extn_publisher][extn_slug]['versions'] %}
{% if extn_versions %}
  {% assign extn_version_latest = extn_versions | first %}
  {% assign extn_latest = extn_version_latest['release'] %}
  {% unless extn_filename == "index.md" %}
    {% assign extn_release = extn_filename | remove: ".md" %}
    {% assign extn_ver = extn_releases | where: "release", extn_release %}
    {% assign extn_version = extn_ver[0] %}
  {% else %}
    {% assign extn_version = extn_versions | first %}
    {% assign extn_release = extn_version['release'] %}
  {% endunless %}
{% endif %}

<!-- BEGIN PAGE OUTPUT -->

<div class="page page-extension-profile">
  {% if page.header_icon or page.header_title %}
    {% include header.html type=extn_type name=page.header_title %}
  {% else %}
    {% include header.html img=extn_icon name=page.name %}
  {% endif %}

  <div class="container">

    {% if extn_versions %}
      <div class="versions-dropdown dropdown page-header-right">
        <button class="page-header-btn" id="version-dropdown" type="button" data-toggle="dropdown" aria-haspopup="true"
                aria-expanded="false">
          {{extn_type | capitalize }} Version {{extn_release}}
          {% if extn_release == extn_latest %}<em>(latest)</em>{% endif %}
          <span class="caret"></span>
        </button>
        <ul class="dropdown-menu dropdown-menu-right" role="menu" aria-labelledby="version-dropdown">
          {% for ver in extn_versions %}
            {% if ver.release == extn_latest %}
              {% assign ver_path = "" %}
            {% else %}
              {% assign ver_path = ver.release | append: ".html" %}
            {% endif %}
            <li {% if extn_release == ver.release %} class="active" {% endif %}>
              <a href="/hub/{{ extn_publisher }}/{{ extn_slug }}/{{ ver_path }}">
                {{ver.release}} {% if ver.release == extn_latest %}<em>(latest)</em>{% endif %}
              </a>
            </li>
          {% endfor %}
        </ul>
      </div>
    {% endif %}

    {% capture full_content %}
      {% unless path_array contains "kong-inc" %}
        <div class="alert alert-info" role="alert">
          Community {{ extn_type | capitalize }}: This plugin is <b>developed, tested, and maintained</b> by a third-party contributor.
        </div>
      {% endunless %}

      {% if page.enterprise %}
        <div class="alert alert-warning">
          <strong>Kong Enterprise only</strong>: This plugin is only available with a <a href="https://konghq.com/kong-enterprise-edition">Kong Enterprise subscription</a>.
        </div>

        Please inquire about Kong Enterprise by <a href="https://konghq.com/request-demo">contacting us</a>, or start a <a href="https://konghq.com/free-trial/">free trial</a> today.
        <hr>
      {% endif %}

      {% if page.alpha %}
      <div class="alert alert-red">WARNING: This functionality is released as an alpha-quality feature. Please proceed with caution.</div>
      {% endif %}

      {{ page.description | markdownify }}

      {% if page.type == "plugin" %}
        <hr>
        <h2 id="terminology">Terminology</h2>
        <ul>
          <li><code>plugin</code>: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.</li>

          {% if page.params.service_id or page.params.route_id %}
            <li><code>Service</code>: the Kong entity representing an external <em>upstream</em> API or microservice.</li>
          {% endif %}
          {% if page.params.route_id %}
            <li><code>Route</code>: the Kong entity representing a way to map downstream requests to upstream services.</li>
          {% endif %}
          {% if page.params.consumer_id %}
            <li><code>Consumer</code>: an entity that makes requests for Kong to proxy; it represents either a user or an external service.</li>
            <li><code>Credential</code>: a unique string associated with a Consumer, also referred to as an API key.</li>
          {% endif %}
            <li><code>Upstream service</code>: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.</li>
          {% if page.params.api_id %}
          <li><code>API</code>: a legacy entity used to represent your upstream services. <strong>Deprecated</strong> in favor of Services since <a href="https://github.com/Kong/kong/blob/master/CHANGELOG.md#0130---20180322">CE 0.13.0</a> and <a href="https://docs.konghq.com/enterprise/changelog/#0-32">EE 0.32</a>.</li>
          {% endif %}
        </ul>
      {% endif %}

      {% if page.installation %}
        <hr>
        <h2 id="installation">Installation</h2>

        {{ page.installation | markdownify }}

        <hr>
      {% endif %}

      {% if page.type == "plugin" %}
        <h2 id="configuration">Configuration</h2>
        {% if page.params.protocols %}
          <p>This plugin is compatible with requests with the following protocols:</p>
          <ul>
            {% for protocol in page.params.protocols %}
              <li><code>{{ protocol }}</code></li>
            {% endfor %}
          </ul>
        {% endif %}

        {% if page.params.dbless_compatible == true %}
          <p>This plugin is <strong>compatible</strong> with DB-less mode.</p>
        {% elsif page.params.dbless_compatible == "partially" %}
          <p>This plugin is <strong>partially compatible</strong> with DB-less mode.</p>
        {% elsif page.params.dbless_compatible != nil %}
          <p>This plugin is <strong>not compatible</strong> with DB-less mode.</p>
        {% endif %}

        {% if page.params.dbless_explanation %}
          {{ page.params.dbless_explanation | markdownify }}
        {% endif %}

        {% if page.params.service_id %}
          {{ plugin_config_for_service | markdownify }}
        {% endif %}
        {% if page.params.route_id %}
          {{ plugin_config_for_route | markdownify }}
        {% endif %}
        {% if page.params.consumer_id %}
          {{ plugin_config_for_consumer | markdownify }}
        {% endif %}
        {% if page.params.api_id %}
          {{ plugin_config_for_api | markdownify }}
        {% endif %}

        <h3 id="global-plugins">Global plugins</h3>

        <ul>
          <li><strong>Using a database</strong>, all plugins can be configured using the <code>http://kong:8001/plugins/</code> endpoint.</li>
          <li><strong>Without a database</strong>, all plugins can be configured via the <code>plugins:</code> entry on the declarative configuration file.</li>
        </ul>

        <p>A plugin which is not associated to any Service, Route, or Consumer (or API, if you are using an older
        version of Kong) is considered "global", and will be run on every request.
        Read the <a href="/latest/admin-api/#add-plugin">Plugin Reference</a> and the
        <a href="/latest/admin-api/#precedence">Plugin Precedence</a> sections for more information.
        </p>

        <h3 id="parameters">Parameters</h3>

        <p>Here's a list of all the parameters which can be used in this plugin's configuration: </p>

        {{ params_table | markdownify }}

      {% endif %}

      {{ page.params.extra | markdownify }}

      {{ content }}

      {% if page.terms_of_service %}
        <h3 id="terms-of-service">Terms of Service</h3>
        {{ page.terms_of_service | markdownify }}
      {% endif %}

      {% if page.privacy_policy %}
        <h3 id="privacy-policy">Privacy Policy</h3>
        {{ page.privacy_policy | markdownify }}
      {% endif %}
    {% endcapture %}

    <aside class="page-navigation">
      <span class="close-sidebar">Close Sidebar</span>
      {% unless page.toc == false %}
        <nav>
          {% include toc.html html=full_content h_min=2 h_max=3 sanitize=true %}
        </nav>
      {% endunless %}

      <table id="about-extn">
        <tr>
          <th colspan="2">About this {{ extn_type | capitalize }}</th>
        </tr>
        <tr class="publisher">
          <td>Made by</td>
          <td>
          {% unless extn_publisher == "kong-inc" %}
            {{ page.publisher }}
          {% else %}
            {% include svgs.html img='team-kong-icon' %}
          {% endunless %}
          </td>
        </tr>
        <tr class="categories">
          <td>Categories</td>
          <td>
            <ul class="categories">
            {% for cat in page.categories %}
              {% assign cat_meta = site.extensions.categories | where: "slug", cat %}
              <li><a href="/hub/#{{ cat_meta[0].slug}}">{{ cat_meta[0].name }}</a>{% unless forloop.last %},{% endunless %}</li>
            {% endfor %}
            </ul>
          </td>
        </tr>
        {% if page.support_url %}
          {% assign support_dom = page.support_url | split: "/" %}
          {% assign support_dom = support_dom[2] | remove: "www." | remove: "support." | remove: "help." | remove: "docs." %}
          {% if support_dom.length > 20 %}{% assign support_dom = "Site" %}{% endif %}
          <tr>
            <td>Support</td>
            <td><a href="{{ page.support_url }}">{{ support_dom | truncate: 15 }}</a></td>
          </tr>
        {% endif %}
        {% if page.source_url or page.license_type %}
          <tr class="source-code">
            <td>Source</td>
            <td>
              <ul>
              {% if page.source_url %}
                <li>
                  <a href="{{ page.source_url }}">Code</a>
                </li>
              {% endif %}
              {% if page.license_type %}
                <li>
                  <a href="https://opensource.org/licenses/{{ page.license_type }}">License ({{ page.license_type }})</a>
                </li>
              {% endif %}
              </ul>
            </td>
          </tr>
        {% endif %}
        {% if page.privacy_policy_url or page.privacy_policy or page.terms_of_service or page.terms_of_service_url %}
          {% if page.privacy_policy_url %}
            {% assign privacy = page.privacy_policy_url %}
          {% elsif page.privacy_policy %}
            {% assign privacy = "#privacy-policy" %}
          {% endif %}
          {% if page.terms_of_service_url %}
            {% assign tos = page.terms_of_service_url %}
          {% elsif page.terms_of_service %}
            {% assign tos = "#terms-of-service" %}
          {% endif %}
          <tr class="legal">
            <td>Legal</td>
            <td>
              <ul>
                {% if privacy %}
                  <li>
                    <a href="{{privacy}}">Privacy</a>
                  </li>
                {% endif %}
                {% if tos %}
                  <li>
                    <a href="{{tos}}">Terms of Service</a>
                  </li>
                {% endif %}
              </ul>
            </td>
          </tr>
        {% endif %}
        {% if compat %}
          <tr class="kong-editions">
            <th colspan="2">
              {% if path_array contains "kong-inc" %}
                Bundled with...
              {% else %}
                Compatibility
              {% endif %}
            </th>
          </tr>
          <tr class="kong-compatibility">
            <td colspan="2">
              <ul class="compat-list">
              {% for v in site.data.kong_versions_ee reversed %}
                {% if ee_compatible contains v.release or ee_incompatible contains v.release %}
                  {% unless first_ee %}
                  <h6>Kong Enterprise</h6>{% assign first_ee = true %}
                  {% endunless %}
                  <li>
                  {% if ee_compatible contains v.release %}
                    <i class="fa fa-check"></i>
                  {% elsif ee_incompatible contains v.release %}
                    <i class="fa fa-times"></i>
                  {% endif %}{{ v.release }}
                  </li>
                {% endif %}
              {% endfor %}
              </ul><ul class="compat-list">
              {% for v in site.data.kong_versions reversed %}
                {% if ce_compatible contains v.release or ce_incompatible contains v.release %}
                  {% unless first_ce %}
                  <h6>Kong Community</h6>{% assign first_ce = true %}
                  {% endunless %}
                  <li>
                  {% if ce_compatible contains v.release %}
                    <i class="fa fa-check"></i>
                  {% elsif ce_incompatible contains v.release %}
                    <i class="fa fa-times"></i>
                  {% endif %}{{ v.release }}
                  </li>
                {% endif %}
              {% endfor %}
              </ul>
            </td>
          </tr>
        {% endif %}
      </table>

    </aside>

    <div class="page-content-container">
      <div class="page-content">
        <div class="content show-anchor-links">
          {{ full_content }}
        </div>
      </div>
    </div>
  </div>
</div>

<!-- {% include intercom.html %} -->
